3D GFX/3D GFX.iso/pcutils/windows/genesis/readme.1st

Text File | 1995-12-30 | 26KB | 502 lines

Welcome to Genesis beta v1.0   (c) Silicon Dream Ltd. 1995

It is important that you read at least the QUICK START section of this
document before unzipping and running Genesis. I apologise for the poor
format of the user documentation (yes, its what your reading now) and
my spelling. The programmer documentation is far more proffessional
and is included in the genvxx.zip file in both Microsoft Word format
and plain text.

Contents of this document:

       A BRIEF RUNDOWN
       PC REQUIREMENTS
       QUICK START
       THE USER GUIDE
         THE VIEW
         THE 3D CURSOR
         CHANGING VIEWPOINT
         SURFACE DIALOG
         TOOLS
           Sphere tool
           Patch tool
           Spin tools
           Diff, Union and Int tools
           Enclosed tool
           Coordinate system editor
           Normal tool
       ROYALTIES ON API USEAGE
       DEVELOPERS NOTE

If you have any questions, queries, praises or verbal abuse then I am
your primary and only point of contact;

Name:         Steven Woodman (otheriwse known as Spike)
Org:          Silicon Dream Ltd.
Email:        [e-mail]
Smail-mail:   Flat 1 Chine view, 5 Mckinley rd, Westbourne,
              Bournemouth, Dorset, UK, BH4 8AG
Tel:          ...ooooh - could be a bad idea
Updates from: - The SimTel20 windows software repository
              - UK's Demon ftp server
              - The Raytech bulletin board on UK tel; 01862 832020
              - Me

Those of you who followed my original append in the
comp.graphics.algorithms and comp.graphics.raytracing newsgroups will
already be familiar with what Genesis is. To those who didn't here's
a brief rundown;

A BRIEF RUNDOWN

Genesis is a new windows based 3D toolkit with a comprehensive set
of programming interfaces. The editor application supplied as part of
Genesis is intended to allow easy and intuitive editing of 3D objects,
textures, lights and animations. My design goal was to try and build
something like a 2D drawing program, BUT IN 3D! The API can be used for
writing 3D applications independent of the editor. On the other hand if
you are interested in writing a 'tool' to do a 3D type job, for instance,
say you want to write some code to take one 3D object and 'bend' it
around another, then the way to do it is to write a 'tool' that plugs
into the editor. The various API's provide you with an excellent platform
to start your work, one in which most of the hard stuff is already done
for you. The Geometry engine is also replaceable meaning Genesis could
support BRender, Glint chips, Windows 3D GDI, Open GL, Renderware,
Playstation, Rendermorphics engine and Intel 3DR to name but a few.

PC REQUIREMENTS

You need;

    * At least a 386 PC WITH a maths copro (or 486DX). Contact
        author for details of non-copro version
    * 4 Megs RAM although 8 is recomended
    * About 3 megs free on hard disk
    * Window 3.x
    * A good graphics card.

The faster your graphics card the better. Also if your card supports true
colour (either 16 bit or 24 bit), this will give better results than an
8 bit colour card. Check your card is in true color mode if it has one.

QUICK START

To get straight into the Genesis editor, do the following;

Make a directory you want to install it in, eg;

    md gen

copy the gen.zip file in, eg;

    cd gen
    copy \gen.zip

unzip this file with the -d and -o options;

    unzip -d -o gen.zip

this will give create you a directory structure containing all of the
Genesis executable files, plus the programmers toolkit and the
documentation needed to start programming.

Start windows (if not already) and create an icon using the windows program
manager's File/Properties menu item. Both the program directory and the
working directory must be set to;

    \gen\bin

or whatever you have called your directory. Copy the Gened.ini file to
the main windows directory, eg;

    copy \gen\bin\gened.ini \windows

NOW RUN GENESIS FROM THE PROGRAM MANAGER ICON! Alternatively you could just
run it from the Program managers File/Run menu item.

The version of Genesis you have is a Freeware copy. Feel free
to play with it, develop for it, give it to your friends and write GOOD
articles about it in magazines. It will NOT explode after 30 days leaving
a nasty mess on your hard disk, however you are limited to a maximum of
1000 polygons. If you would like an unresricted version, this is available
from the author for a small fee of 20 quid (which includes posting fee and
cost of disks if neccessary). If you are interested in developing tools,
Geometry engines or applications, please read the developers note at the
bottom of this document.

Now follow the user guide...

THE USER GUIDE

When the editor starts you will see the main editor window and in it a couple
of view windows, a tool bar at the top, a status bar at the bottom, and a
control bar on the right hand side. At the top of the control bar you will see
the 'toolbox'. Each icon in here is actually a button which invokes one of the
tools.

At this point it is quite likely that you have already been messing around with
the program for about 10 minutes and have got yourself confused, or the program
confused and have then resorted back to the documentation. (I often do this
too).

Before I go on let me remind you that Genesis is a version 1 beta, so it
is incomplete and yes, it has bugs! You might find that some very basic
operations are still not supported, I am not yet too worried about this as
generally this is just a matter of writing the tools for the job. At present
I am more concerned with getting the API's and supporting framework finished
and tested.

OK, enough excuses, lets continue with the user documentation;

The two views represent two 'scenes'. A bit like two documents in a
word processor. One view has a default object in it (just so you can mess
around rendering stuff). The other has nothing in it and can be used to
experiment with the tools. Click in the view called start.gen to make it
active (start.gen is the name of the model file loaded from the \bin
directory). Start.gen is a model of an everday goblet with a silvery brick
texture on it containing a gold sphere, the sort of thing commonly found in
glass cabinets! Actually its really just to show off the surface types.

THE VIEW

The view is a window into a scene. There can be more than one view per scene.
Select the Window/New Window menu item for another view into the active scene.
In the view you will see the x, y and z axis drawn, along with a grid in the
zx plane. The grid can be changed or switched off from the control panel. The
entire overlay can be switched off using the View/No overlay menu item. The
grid can also be switched to solid lines or points from the View menu (points
take longer to draw).

Sort of bug: Changing the size of the view window causes a re-render with a
             different aspect ratio. This will soon change so you cant easily
             make your view all squashed up.

THE 3D CURSOR

If you hold the left mouse button down in the view and move the mouse the
mouse cursor disappears and you find that you can move a 3D cursor around in
the view. If you move left to right or vice versa then the cursor moves in the
most horizontal axis in the view. If its moved up/down then the 3D cursor
moves in the most vertical axis. Unless you change the view orientation this
will be the x and y axis. To move in z hold down the right button and move up
and down.

Bug: Sometimes from some views the cursor moves in the opposite direction you
     expect. All adds to the fun!

CHANGING VIEWPOINT

To change the direction in which you are looking into the scene position the
cursor and press the DIR. button on the control panel. The next time a render
is done you will look towards the new position. To render press the cube shaped
button on the tool bar below the menu bar (not the toolbox!). Alternatively
the File/Render menu item can be used. To change the position you are looking
from, position the cursor and press the POS. buttton. The In and Out buttons on
the control bar can be used to zoom in and out (all quite intuitive really),
and the Back button can be used to step back through all the previous views
rendered. So if you screw up and find yourself staring into blank space, just
press Back.

The Up button changes the up direction in the rendered image.

SURFACE DIALOG

To edit the surface type of the goblet select the Scene/Surfaces menu item.
The dialog shows the properties of the currently defined surfaces. To change
the brick texture to a more natural looking concrete, click on the preview
picture of the brick surface, then on the filename Browse button and select
the conctex.bmp. When the image is rendered it will have the new texure. The
preview is a model which is rendered in real-time. You can change the type of
the preview model from the dialog.

Other options allow you to change wether or not the texture is infinetly tiled,
and the type of specular reflections the surface generates. The 'dull' spec
reflection actually produces no highlights. Silver produces large bright
highlights, Gold produces large dull highlights. Glass gives you very small
highlights just around the edges of your object. Linear and Constant are also
implemented but the rest just do the same as glass. Notice that selecting these
options does not change the colour of your object - just the highlights. To
change the colour switch off texturing for this surface and press the colour
button.

Any windows bitmap file can be used to make a new texture. See the coordinate
system editor section on how to specify the orientation of the texture.

Bug: I lied, currently only 8 bit (256 col.) and 24 bit bitmaps work!

The 'more' button is used to define recursive textures and bump mapping,
neither of which the default Geometry engine support, so messing around with
these options will have no effect.

TOOLS

Sphere tool

Now go to the blank view. To invoke a tool, say the sphere, click on its
button in the toolbox (second one in). The Tool/Configure menu item can now
be used to configure the sphere tool. Use this to change to a smooth sphere
and OK the dialog. Position the cursor for the center of the sphere and press
the 'Set' button on the control panel. Then move the cursor to a point on the
radius and press the 'Do' button. The surface is coloured with the currently
selected surface type from the surface dialog box (the one you clicked in last).

A new object called 'sphere' will appear in the object listbox. If you create
a second sphere object it will be called 'sphere2'. This applies to all tools
that create objects.

The 'Mapped texture' checkbox in the sphere config dialog will be used for
warping a texture into a spherical map so that the image doesn't distort across
the surface of the sphere. If you think I'm talking cac please ignore the last
sentance.

All tools that create primitive objects or bits of objects use the currently
selected surface type. The grand list currently consists of; Patch, Sphere
and Spin tools (the first, second and seventh respectively in the toolbox).

Bug: You can change the 'Number of verticies' field in the configuration
     of the sphere but some values will cause the code to crash. The number
     is only an approximate indication anyway

Patch tool

The most basic of all tools, enables you to create a patch or polygon by
positioning the cursor and pressing 'Set' for as many verticies as are needed.
The patch tool is the first one in the box by the way (if theres one thing I
learnt its that doing 3D icons is harder than 2D ones). Use 'Do' to create
the patch. All points must lie on a plane but you are not limited to how many
points you create. You can define a 1,000 point concave outline and as long
as all the points lie on a plane then Genesis will split it up into lots of
small patches (of up to 4 verticies each). Each patch has a solid and an empty
side. The patch must always be seen from the solid side as it will actually
become invisible if seen from the wrong side. You implicitly define which
side is solid by ALWAYS drawing the verticies CLOCKWISE as seen from the
outside.

You must also select which object in your scene you want the patch
to belong to. Do this by highlighting the 'start' object name in the rightmost
listbox on the control panel. The 'start' object is initially empty.

Was that a bit un-intuitive? If it was then you will find yourself very
rarely actually using this tool as other more powerfull ones actually build
whole objects for you.

Spin tool

This allows you to define an outline which is spun around an axis to form a
cylindrical type formation. The goblet was done using this technique. Select
the tool (7th one in toolbox). Position the cursor at a point at the start of
the axis you want to spin in and press 'Set'. Then position the cursor at the
end of the spin axis and press 'Set' again. You will then be presented with
an outline editor. The vertical axis of the editor is the line you have just
drawn in 3D. Each press of the mouse button in the editor defines a new
segment to be added to the outline.

If you want to create a disconnected part of the outline use the 'move'
button. If you want to create an arc, circle or box as part of the outline,
press 'move' and position the 2D outline cursor at the center of the
arc/circle or corner of the box. Then position the cursor at a point on the
radius or the other corner and press the appropriate button at the bottom
of the editor. When you OK the dialog a wireframe is drawn in the view, if
you're happy with it press 'Do', otherwise you can reposition the end of the
spin axis and press 'Set' again to get the outline editor back.

IMPORTANT NOTE: Consider this. In the outline editor you define a line segment
        coming out from the bottom of the vetical axis and extending
        right. Then another segment goes straight up. Now given that
        patches have a solid and an empty side, have you defined a
        sort of cylinder (solid on the inside, where the spin axis is)
        or a sort of cylindrical hole which is solid on the outside
        (and empty space where the axis is). The answer is you have
        defined a solid cylinder because the outline is always solid
        on the left hand side as you draw it. If you 'moved' to the
        end of the cylinder first and then drew down to the axis
        origin, then would would have defined a cylindrical hole!
        When defining arcs and circles a negative arc angle makes
        the outline proceed clockwise instead of anticlockwise
        (ie. giving hole type outlines instead of solid ones).

The Spin tool has a configuration dialog box which is accessed the same as
for the sphere.

Diff, Union an Int tools

These tools are more complex than the others, (and took longer to write).
Having created two objects such as a sphere and a spin object you will notice
that their names appear in the right hand list box on the control panel.
If these two objects overlap in space then using these tools you can perform
a CSG (constructive solid geometry) (sometimes called boolean) operation on
the objects. The diff tool (3rd one in) subtracts one object from another.
Highlight the names of the two objects in the listbox, select the tool, and
press 'Do'. Indicate on the dialog which object is subtracted from which, and
thats all! When the operation is complete the all views into the scene are
re-rendered. The union tool joins two objects together such that the patches
form a continuous mesh across the surface. The intersection tool takes only
the overlapping part of the two objects. After the operation only one object
will be listed in the object listbox with a name like 'diff object', 'union
object' or 'int object'.

The configuration dialog boxes for these tools allow you to specify how the
smoothing is to be performed if a curved patch from one object joins a curved
patch from the other in the resulting object.

Enclosed tool

I said earlier that all patches have a solid and an empty side, and that if
you view it from the wrong side it will become invisible. This is OK because
each object should be a continous polygon mesh surface, in other words each
edge of each patch should be connected to another patch thereby preventing
you seeing the wrong side of any particular patch. Unless of course you intend
to view the object from the inside in which case you should design its inside
as another continuous polygon mesh belonging to the same object!

If an object isn't a continous mesh nothing will go wrong, its just it might
look like you have holes in it when seen from certain angles (ie. when
looking at the inside of patches). What is more the CSG tools will warn
you if either object is not completely enclosed as sometimes the results
you get from un-enclosed objects might not be what you expected.

So to cut through the waffle, the enclosed tool highlights any unconnected
edges in all objects in your scene. When developing tools this can also act as
a debugger to check your tool is giving sensible results. To try it out
simply create a patch and select the enclosed tool (6th one in toolbox).

It has no configuration dialog.

Bug: Very occasionally the CSG tools will generate an object with unconnected
     edges.

Coordinate system editor

The coordinate system editor (8th tool) is a very powerfull tool. It doesn't
work on objects themselves but on the coordinate systems they belong too.
So far both of the scenes you have been experimenting with have each had a
single coordinate system. The left hand listbox of the control panel contains
a list of the coordinate systems belonging to the active scene.

OK, let me start by posing some problems, then maybe the significance of
coordinate systems will become more obvious;

      Prob 1. You have designed a large cube with one corner at the origin.
              You now want add a load of primitives (spheres, blocks etc.)
              such that they appear to be sitting on one of the faces of the
              cube. However the face you have chosen is the back vertical
              face! Even if you re-position the viewpoint so you can see what
              you are doing you are used to working on a flat horizontal
              surface not a vertical one and have trouble adjusting. Worst
              still suppose the face isn't exactly aligned with one of the
              axis, you will have terrible trouble knowing wether your new
              primitives are actually sitting on the surface, penetrating
              it, or sitting too high above it. also some primitive creation
              tools might only create primitives algined with the axis.

      Prob 2. When defining a texture, the bitmap you use is placed in the
              xy plane of the coordinate system. If your bitmap is 100 pixels
              wide by 80 high then the extent of the texture will be from the
              origin to x=100 and y=80 (if not tiled) and will be projected
              through the z. Suppose you want the texture scaled to x=1000
              to y=800 or projected down through the zx plane.

      Prob 3. You are using an animation tool. You have a landscape and within
              it a river. On the river is two boats; A and B. Boat A has 10
              people on it. When the boat moves relative to the landscape all
              the people on the boat must also move (otherwise they will end
              up suspended above the river!), BUT the people must still be
              able to move about on the boat. Boat B obviously moves
              indepentently of boat A. You need a way of telling the editor
              that the people objects of Boat A must move when the Boat A
              object moves and likewise for Boat B.

The answer to all these problems is coordinate systems. The coordinate system
editor tool enables you to define a new coordinate system relative to the
currently active one (which is called 'top level' unless you've already
created some). The new coordinate becomes a 'child' of the active one and the
three buttons at the bottom of the coor sys editor dialog allow you to
reposition and scale it relative to its parent. When you create a new coordinate
system (using the 'New' button) a new view is automatically created for you.

To modify a coordinate system relative to its parent, first make it active
(by clicking in its view, or selecting its name from the coor sys listbox).
Then click the 'Modify' button. The tool then makes its parent's view
active and draws a represention of its axis's within its parent. Then
using the Origin->Cursor button you can move the origin, and using the
Z Axis->Cursor button you can specify a direction towards which the z axis
should point. The third button; Y Dir->Cursor can be used give an aproximate
direction to the Y axis given the constraints of the origin and the z axis.

The new view can be used exactly like its parents view but what you have
really done is turned the world on its head so that you can work with a
sensible set of axis, while the rest of the world (ie. everything defined in
the parent coor sys) is at an awkward angle.

You can define a coordinate system purely for the purpose of defining a texture
position. The surface type dialog has a combo-box field where you can tell
it the name of the coor sys the texture is defined in. You can then close down
the view if your not going to be working in it (this doesn't delete the coor
sys).

In the Prob 3 example boats A and B will each have their own coordinate
system which is a child of 'top level'. The landscape will be defined in
'top level' by a bunch of patches. The individual people of boat A will each
have their own coordinate system (as they can all move independently of each
other) but they will all be children of the boat A coordinate system (as they
must move if the boat moves). Boat B will likewise have its own coordinate
system as a child of 'top level'.

Normal tool

The normal tool (last one in the box) draws onto the view the normal (or
arrow perpendicular to the surface) of each every curved patch facing the
view. Since the tools described create the normals for you, you will rarely
need to use this, however eventually this tool will enable you to 'grab' a
normal with the mouse and bend it, thereby changing the shading at that
point on the surface. Even then this tool is really just for perfectionists
who maybe dont like default smoothing effect of some tools.

The normal tool will be good for doing things like, putting a dent in the
side of your object, eg. a dented, brick coloured goblet, with a dented gold
globe in it! Obviously there is no limit to your creative potential.

...Watch out for more tools

ROYALTIES ON API USEAGE

I must apologies to those whom I told the API was free to use in your own
programs. Dont worry just yet - please hear me out. I was strongly advised
for copyright reasons to demand a small royalty fee on use of the API. I
want to keep this as low as possible as I want to encourage people to use
the API. If you want to use the API in an application or tool that will be
sold for profit, then a small royalty fee of 2% of the retail value of the
product will be charged on each unit sold. 1% if any part of the maths,
debug or Helper API's are used without the Geometry API. This note applies
to use of the API's irrespective of wether the libraries themselves are used.

DEVELOPERS NOTE

I think this is the bit a lot of people have been waiting for. This is the
agreement; This version of Genesis is Freeware. Soon there will be
a commercial release. The more tools and/or Geometry engine's it supports
the better, so if you are interested in developing for it, send me what you
have and if its of general use to others (ie. no spinal column fracture
detectors please) it will be included. This is your chance to get your name
in lights and obviously a royalty payment in your pocket. The initial release
will be under £100 (pounds) unless there is such a wealth of tools that
puts us way above the competition. This would be nice but I'm trying to
be realistic. I will have to work out fairly on an individual basis the
royalty payment based on effort put in and value it adds to the package as
a whole.

From the overwhelming response I had to my original append I'm sure this is
going to take off in a big way. I will endevour to set up a Genesis newsgroup
so that developers can talk to each other and help each other with their
problems. This will also serve to ensure that developers aren't writing the
same tools (.DXF loader anyone?).

I am of course still working on Genesis and have my own schedule, however if
there are areas you would like completed sooner rather than later in order
to develop tools then feel free to E-mail me a request.

Once again, Genesis (particularly the editor and the tool interface) is not
complete by a long way. I am confident that by the time we reach first release
which hopefully will be well within a year, it will be one of if not the most
powerfull PC based 3D graphics development tools available.